Skip to content

fix(settings): remove markdownlint exclusion for collections/*.collection.md#1372

Merged
katriendg merged 11 commits into
microsoft:mainfrom
PratikWayase:fix/markdownlint-collections
May 12, 2026
Merged

fix(settings): remove markdownlint exclusion for collections/*.collection.md#1372
katriendg merged 11 commits into
microsoft:mainfrom
PratikWayase:fix/markdownlint-collections

Conversation

@PratikWayase
Copy link
Copy Markdown
Contributor

@PratikWayase PratikWayase commented Apr 16, 2026

Pull Request

Description

Removed the exclusion for collections/*.collection.md from markdownlint configuration and fixed all related lint violations across collection files.

Changes include:

  • Added top-level headings to all collection files (MD041)
  • Removed multiple consecutive blank lines (MD012)
  • Replaced em dashes with compliant alternatives
  • Standardized formatting and ensured newline consistency
  • Updated Validate-MarkdownFrontmatter.ps1 to align with updated linting rules

Related Issue(s)

Closes #1341

Type of Change

Select all that apply:

Code & Documentation:

  • Bug fix (non-breaking change fixing an issue)
  • New feature (non-breaking change adding functionality)
  • Breaking change (fix or feature causing existing functionality to change)
  • Documentation update

Infrastructure & Configuration:

  • GitHub Actions workflow
  • Linting configuration (markdown, PowerShell, etc.)
  • Security configuration
  • DevContainer configuration
  • Dependency update

AI Artifacts:

  • Reviewed contribution with prompt-builder agent and addressed all feedback
  • Copilot instructions (.github/instructions/*.instructions.md)
  • Copilot prompt (.github/prompts/*.prompt.md)
  • Copilot agent (.github/agents/*.agent.md)
  • Copilot skill (.github/skills/*/SKILL.md)

Other:

  • Script/automation (.ps1, .sh, .py)
  • Other (please describe):

Testing

  • Ran: npx markdownlint-cli2 "collections/*.collection.md" → 0 errors
  • Ran: npm run lint:md → 0 errors
  • Verified no regressions in markdown linting across repository

Checklist

Required Checks

  • Documentation is updated (if applicable)
  • Files follow existing naming conventions
  • Changes are backwards compatible (if applicable)
  • Tests added for new functionality (not applicable)

AI Artifact Contributions

  • Used /prompt-analyze to review contribution
  • Addressed all feedback from prompt-builder review
  • Verified contribution follows common standards and type-specific requirements

Required Automated Checks

  • Markdown linting: npm run lint:md
  • Spell checking: npm run spell-check
  • Frontmatter validation: npm run lint:frontmatter
  • Skill structure validation: npm run validate:skills
  • Link validation: npm run lint:md-links
  • PowerShell analysis: npm run lint:ps
  • Plugin freshness: npm run plugin:generate
  • Docusaurus tests: npm run docs:test

Security Considerations

  • This PR does not contain any sensitive or NDA information
  • Any new dependencies have been reviewed for security issues (none added)
  • Security-related scripts follow the principle of least privilege

@PratikWayase PratikWayase requested a review from a team as a code owner April 16, 2026 05:21
@katriendg
Copy link
Copy Markdown
Contributor

katriendg commented Apr 16, 2026

Thanks for your contribution @PratikWayase - I believe it will be good to hold off the changes on the collection MD files until PR #1316 is merged as it touches the same files, and you may have some conflicts. FYI @WilliamBerryiii

@WilliamBerryiii WilliamBerryiii changed the title Fix : Remove markdownlint exclusion for collections/*.collection.md #1341 fix(settings): remove markdownlint exclusion for collections/*.collection.md Apr 23, 2026
@katriendg
Copy link
Copy Markdown
Contributor

katriendg commented Apr 23, 2026

Thanks for your work on this one @PratikWayase, nothing we have a PR out that needs to be merged first, and simplifies some of the work: #1316. Then this one can be rebased and simplified:

After #1316 merges, the auto-generated artifact tables will be lint-compliant by construction. The only pieces of which would still be needed are:

  • Removing the .markdownlint-cli2.jsonc exclusion
  • Removing the Validate-MarkdownFrontmatter.ps1 exclusion
  • Fixing any em dashes remaining in the hand-authored intro sections (above the markers)

Thank you for your patience

WilliamBerryiii
WilliamBerryiii requested changes Apr 23, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@WilliamBerryiii WilliamBerryiii left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you so much for picking up #1341, @PratikWayase! The em-dash cleanup, the conversion away from bold-prefix list items, and adding H1s for MD041 all landed cleanly across the 14 collection files, and that is exactly the writing-style direction we have been moving toward. We really appreciate the care you put into this.

Before we merge, we left a few inline suggestions we would love your help tightening up. Happy to pair on any of these if it would be easier.

One last small note for after we land this: please run npm run plugin:generate as the final step so the plugins/ outputs and extension/README.*.md regenerate from the updated collection bodies. Those files are generated, so they need to flow through after the source changes.

Thank you again for tackling this, @PratikWayase. The writing-style improvements here are genuinely useful, and we are looking forward to getting this merged once the items below are sorted. Let us know if you would like a hand with any of them.

Comment thread scripts/linting/Validate-MarkdownFrontmatter.ps1
Comment thread .markdownlint-cli2.jsonc
Comment thread collections/ado.collection.md Outdated
Comment thread collections/ado.collection.md Outdated
Comment thread collections/design-thinking.collection.md Outdated
@MauroDruwel MauroDruwel mentioned this pull request Apr 23, 2026
Closed
@WilliamBerryiii
Copy link
Copy Markdown
Member

WilliamBerryiii commented Apr 28, 2026

Hi @PratikWayase — thanks for picking this up.

Quick status update: PR #1316 merged after you opened this, and it changed the contract for collections/*.collection.md. The artifact tables are now machine-generated by npm run plugin:generate between <!-- BEGIN AUTO-GENERATED ARTIFACTS --> / <!-- END AUTO-GENERATED ARTIFACTS --> markers, so most of the current diff lands inside zones that get overwritten on the next regeneration.

Rather than ask you to redo a large rebase, I'm going to push a rework directly to this branch with you kept as the commit author so you retain credit for #1341. The new shape is much smaller:

  • Remove collections/*.collection.md from ignores in .markdownlint-cli2.jsonc.
  • Update the inline justification in scripts/linting/Validate-MarkdownFrontmatter.ps1 (the exclusion stays — these files are marker-bearing generated docs without frontmatter).
  • Replace em-dashes only in the hand-authored intro lines (above the BEGIN AUTO-GENERATED ARTIFACTS marker) of each *.collection.md.
  • Run npm run plugin:generate and npm run lint:all and verify clean.

Two asks before I push:

  1. Please confirm "Allow edits from maintainers" is still enabled on this PR (it's the default for fork PRs, but worth checking).
  2. If you have any local work-in-progress on fix/markdownlint-collections, push it now or let me know — I'll be force-pushing a rewritten history.

I'll hold off ~24h for your reply, then proceed. Appreciate the contribution.

@PratikWayase
Copy link
Copy Markdown
Contributor Author

PratikWayase commented Apr 29, 2026

Yes, "Allow edits from maintainers" is enabled. Feel free to proceed.

@PratikWayase @WilliamBerryiii
fix(collections): enable markdownlint for collections/*.collection.md
c5b7982 
- remove collections/*.collection.md from .markdownlint-cli2.jsonc ignores
- add H1 titles, Included Artifacts headings, and blockquote previews to all 13 collection manifests
- replace em-dashes with hyphens in design-thinking instructions/prompts frontmatter and in-scope docs
- update Prepare-Extension.ps1 generator to emit Included Artifacts header
- regenerate plugins/**/README.md for all 13 collections

Closes microsoft#1341

🧹 - Generated by Copilot

Co-authored-by: WilliamBerryiii <williamberry@github.com>
@WilliamBerryiii WilliamBerryiii force-pushed the fix/markdownlint-collections branch from 85bfea2 to c5b7982 Compare April 30, 2026 02:08
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 30, 2026 •
edited
Loading

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.53%. Comparing base (8d3b095) to head (7a4e493).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #1372      +/-   ##
==========================================
+ Coverage   85.46%   86.53%   +1.06%     
==========================================
  Files          82       76       -6     
  Lines       11802    10746    -1056     
==========================================
- Hits        10087     9299     -788     
+ Misses       1715     1447     -268
Flag Coverage Δ
pester 83.65% <100.00%> (+0.04%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
scripts/extension/Prepare-Extension.ps1 94.52% <100.00%> (ø)
scripts/plugins/Modules/PluginHelpers.psm1 94.13% <100.00%> (+1.45%) ⬆️

... and 8 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@katriendg
Copy link
Copy Markdown
Contributor

katriendg commented May 11, 2026

@PratikWayase @WilliamBerryiii - while doing a validation, I noticed duplicate headings H1 generated, so now updated that in the generation script. Pushed the update and looks good to me, we should be able to merge now.

@katriendg katriendg merged commit 42cc137 into microsoft:main May 12, 2026
50 checks passed
This was referenced May 12, 2026
Open
Open
@github-actions github-actions Bot mentioned this pull request May 12, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@katriendg katriendg katriendg approved these changes

@WilliamBerryiii WilliamBerryiii WilliamBerryiii approved these changes

@bindsi bindsi bindsi approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Remove markdownlint exclusion for collections/*.collection.md

5 participants

@PratikWayase @katriendg @WilliamBerryiii @codecov-commenter @bindsi